#ifndef DEVICE_STATE_MANAGER_H
#define DEVICE_STATE_MANAGER_H

#include <Arduino.h>
#include <freertos/FreeRTOS.h>
#include <freertos/semphr.h>
#include <ArduinoJson.h>

// 前向声明
class LEDManager;
class LEDControlCenter;

/**
 * @class DeviceStateManager
 * @brief 设备状态管理器
 * 
 * 统一管理设备的各种状态信息，提供线程安全的状态查询和更新接口。
 * 支持状态变化回调、状态持久化、状态转换验证等高级功能。
 * 
 * @author ESP32沙画绘图机项目组
 * @date 2025年9月18日
 * @version 2.0 (优化版本)
 */

// ==================== 系统常量定义 ====================
namespace DeviceStateConfig {
  // 线程安全相关常量
  static constexpr TickType_t MUTEX_TIMEOUT_MS = 1000;           // 互斥锁超时时间（毫秒）
  static constexpr uint32_t MUTEX_TAKE_RETRY = 3;                // 互斥锁获取重试次数
  
  // 状态报告相关常量
  static constexpr size_t STATUS_REPORT_BUFFER_SIZE = 512;       // 状态报告缓冲区大小
  static constexpr size_t JSON_DOCUMENT_SIZE = 1024;             // JSON文档大小
  
  // 性能优化常量
  static constexpr uint32_t STATE_CACHE_VALID_MS = 100;          // 状态缓存有效时间（毫秒）
  static constexpr uint8_t MAX_STATE_HISTORY = 10;               // 最大状态历史记录数
  
  // 绘图会话相关常量
  static constexpr uint32_t MAX_PATTERN_NAME_LENGTH = 64;        // 最大图案名称长度
  static constexpr uint32_t DRAWING_PROGRESS_UPDATE_INTERVAL = 50; // 绘图进度更新间隔（毫秒）
}

// ==================== 状态枚举定义 ====================

/**
 * @enum SystemState
 * @brief 系统工作状态枚举
 */
enum SystemState : uint8_t {
  STATE_IDLE = 0,       // 空闲状态 - 系统就绪，可接受命令
  STATE_HOMING,         // 回零状态 - 电机正在执行回零操作
  STATE_DRAWING,        // 绘图状态 - 正在执行绘图任务
  STATE_EMERGENCY,      // 紧急停止状态 - 系统出现紧急情况，需要停止所有操作
  STATE_MAINTENANCE,    // 维护状态 - 系统进入维护模式
  STATE_MAX            // 状态总数，用于验证
};

/**
 * @enum DeviceRunState
 * @brief 设备运行状态枚举
 */
enum DeviceRunState : uint8_t {
  DEVICE_SLEEPING = 0, // 休眠状态 - 电机禁用，降低功耗
  DEVICE_ACTIVE,       // 活跃状态 - 电机启用，系统正常运行
  DEVICE_STANDBY,      // 待机状态 - 部分功能休眠，快速唤醒
  DEVICE_MAX          // 状态总数，用于验证
};

/**
 * @enum NetworkState
 * @brief 网络连接状态枚举
 */
enum NetworkState : uint8_t {
  NETWORK_DISCONNECTED = 0, // 网络断开 - 无网络连接
  NETWORK_CONNECTING,       // 正在连接 - WiFi连接过程中
  NETWORK_CONNECTED,        // 网络已连接 - WiFi连接成功，但MQTT未连接
  NETWORK_MQTT_CONNECTED,   // MQTT已连接 - 完整网络功能可用
  NETWORK_ERROR,           // 网络错误 - 网络连接出现问题
  NETWORK_MAX             // 状态总数，用于验证
};

// ==================== 数据结构定义 ====================

/**
 * @struct StateTransition
 * @brief 状态转换记录结构
 */
struct StateTransition {
  SystemState fromState;        // 源状态
  SystemState toState;          // 目标状态
  unsigned long timestamp;      // 转换时间戳
  String reason;               // 转换原因
};

/**
 * @struct DrawingSession
 * @brief 绘图会话状态结构
 */
struct DrawingSession {
  bool isActive;                // 是否正在绘图会话中
  bool isPaused;                // 是否暂停
  bool isStreamMode;            // 是否为流式模式
  uint32_t currentIndex;        // 当前绘制索引
  uint32_t totalPoints;         // 总点数
  char patternName[DeviceStateConfig::MAX_PATTERN_NAME_LENGTH]; // 当前图案名称
  unsigned long startTime;      // 会话开始时间
  unsigned long lastUpdateTime; // 最后更新时间
  float progressPercent;        // 绘图进度百分比
  uint32_t estimatedTimeLeft;   // 预计剩余时间（秒）
  
  // 构造函数
  DrawingSession() {
    reset();
  }
  
  // 重置会话
  void reset() {
    isActive = false;
    isPaused = false;
    isStreamMode = false;
    currentIndex = 0;
    totalPoints = 0;
    memset(patternName, 0, sizeof(patternName));
    startTime = 0;
    lastUpdateTime = 0;
    progressPercent = 0.0f;
    estimatedTimeLeft = 0;
  }
  
  // 设置图案名称（安全版本）
  void setPatternName(const String& name) {
    strncpy(patternName, name.c_str(), sizeof(patternName) - 1);
    patternName[sizeof(patternName) - 1] = '\0';
  }
  
  // 获取图案名称
  String getPatternName() const {
    return String(patternName);
  }
};

// ==================== 主类定义 ====================

class DeviceStateManager {
private:
  // ==================== 核心状态变量 ====================
  SystemState systemState;           // 当前系统状态
  DeviceRunState deviceState;        // 当前设备运行状态
  NetworkState networkState;         // 当前网络状态
  DrawingSession drawingSession;     // 绘图会话信息
  
  // ==================== 状态缓存和历史 ====================
  SystemState cachedSystemState;     // 缓存的系统状态
  unsigned long lastCacheUpdate;     // 最后缓存更新时间
  StateTransition stateHistory[DeviceStateConfig::MAX_STATE_HISTORY]; // 状态历史
  uint8_t historyIndex;              // 历史记录索引
  uint8_t historyCount;              // 历史记录数量
  
  // ==================== 外部依赖 ====================
  LEDControlCenter* ledControlCenter; // LED控制中心引用
  
  // ==================== 线程安全保护 ====================
  SemaphoreHandle_t stateMutex;      // 状态保护互斥锁
  SemaphoreHandle_t historyMutex;    // 历史记录保护互斥锁
  
  // ==================== 回调函数 ====================
  void (*stateChangeCallback)(SystemState oldState, SystemState newState);
  void (*networkStateCallback)(NetworkState oldState, NetworkState newState);
  void (*drawingProgressCallback)(uint32_t currentIndex, uint32_t totalPoints);
  
  // ==================== 内部辅助方法 ====================
  bool takeMutexWithRetry(SemaphoreHandle_t mutex, TickType_t timeout = DeviceStateConfig::MUTEX_TIMEOUT_MS);
  void addStateToHistory(SystemState fromState, SystemState toState, const String& reason);
  bool isValidStateTransition(SystemState fromState, SystemState toState);
  void updateStateCache();
  String stateToString(SystemState state);
  String deviceStateToString(DeviceRunState state);
  String networkStateToString(NetworkState state);

public:
  // ==================== 构造和析构 ====================
  DeviceStateManager();
  ~DeviceStateManager();
  
  // ==================== 初始化方法 ====================
  bool begin(LEDControlCenter* ledControl = nullptr);
  void reset();
  
  // ==================== 系统状态管理 ====================
  bool setSystemState(SystemState newState, const String& reason = "");
  SystemState getSystemState(bool useCache = true);
  String getSystemStateString(bool useCache = true);
  
  // ==================== 设备运行状态管理 ====================
  bool setDeviceState(DeviceRunState newState, const String& reason = "");
  DeviceRunState getDeviceState();
  String getDeviceStateString();
  bool isDeviceActive();
  bool isDeviceSleeping();
  
  // ==================== 网络状态管理 ====================
  bool setNetworkState(NetworkState newState, const String& reason = "");
  NetworkState getNetworkState();
  String getNetworkStateString();
  bool isNetworkConnected();
  bool isMQTTConnected();
  
  // ==================== 绘图会话管理 ====================
  bool startDrawingSession(const String& patternName, uint32_t totalPoints, bool isStreamMode = false);
  bool pauseDrawingSession(uint32_t currentIndex);
  bool resumeDrawingSession();
  bool endDrawingSession();
  bool updateDrawingProgress(uint32_t currentIndex);
  DrawingSession getDrawingSession();
  bool isDrawingActive();
  bool isDrawingPaused();
  float getDrawingProgress();
  uint32_t getEstimatedTimeLeft();
  
  // ==================== 状态查询和报告 ====================
  String getStatusReport();
  String getDetailedStatus();
  String getStatusJson(bool includeHistory = false);
  String getDrawingSessionJson();
  
  // ==================== 状态历史管理 ====================
  void clearStateHistory();
  String getStateHistoryJson();
  StateTransition getLastStateTransition();
  
  // ==================== 回调设置 ====================
  void setStateChangeCallback(void (*callback)(SystemState, SystemState));
  void setNetworkStateCallback(void (*callback)(NetworkState, NetworkState));
  void setDrawingProgressCallback(void (*callback)(uint32_t, uint32_t));
  
  // ==================== 状态验证方法 ====================
  bool canStartDrawing();
  bool canStartHoming();
  bool canExecuteMotorCommand();
  bool canEnterSleepMode();
  bool canConnectNetwork();
  
  // ==================== 批量操作方法 ====================
  void getAllStates(SystemState& sysState, DeviceRunState& devState, NetworkState& netState);
  bool setAllStates(SystemState sysState, DeviceRunState devState, NetworkState netState);
};

#endif // DEVICE_STATE_MANAGER_H
